When writing tests you can document those tests using JavaDoc tags, that are then transformed into this document you are reading right now. Using these tags is a really simple and you only need to know some HTML if you want to make your documentation look a bit neater. Here are the list of available documentation tags that you can use within your tags and also to document any new features built into DTF.
For examples on using these tags just have a look at any source file with '@dtf.feature' or '@dtf.tag' taglets in them and you'll find various examples on how to use this feature to better the documentation of your code.
| Class Taglets | |
|---|---|
| Taglet | Description |
| @dtf.tag tag | This tag is required to identify that the following documentation is for a tag named tag. |
| @dtf.tag.desc desc | This is where you can place a detailed description of what this tag does and what other resources are useful for reading before using this tag. You can place almost any HTML elements in this section which allows you to format your documentation nicely using tables and lists. |
| @dtf.author author | Here you can put the author or authors names who are responsible for maintaining this tag. |
| @dtf.since version | Just a simple indication of since when this tag has existed in terms of versions of DTF. |
| @dtf.event name | This taglet is used to document exactly what events are being thrown by the tag being documented. This makes the life of the test writer really simple because he/she can consult this documentation to easily identify what information is available from executing this tag. |
| @dtf.event.attr name | With this taglet you can identify all the names of attributes that an event has so that the test writer knows exactly what he/she can get back from executing your tag. This tag depends on the previously documented event name so be sure to use the '@dtf.event' taglet before this one. |
| @dtf.event.attr.desc desc | This taglet is used to describe the previously identified attribute using the @dtf.event.attr taglet. So be sure to use that taglet previous to this one otherwise logically the documentation won't make sense. |
| @dtf.example example | This tag can be used to identify example XML documentation that shows exact XML samples of how to use the tag being documented. So the body of this taglet can be any XML you'd like just be sure to place a single root element around your XML. |
| Attribute Taglets | |
|---|---|
| Taglet | Description |
| @dtf.attr name | This identifies the name of the attribute being documented here. |
| @dtf.attr.desc desc | This is where you can place the description of the attribute being documented.You can place almost any HTML elements in this section which allows you to format your documentation nicely using tables and lists. |
| Utility Taglets | |
|---|---|
| Taglet | Description |
| @dtf.link name | This tag allows you to create a link to another tag/feature just by having the correct name specified. The name is case insensitive so that you don't have to know the exact case spelling of the tag or feature you're trying to link to. |
The feature documentation allows the developer to document features that may not be a simple XML tag and instead could be the documentation of how certain dynamic properties work or the documentation on how ranges work.
The only two things you need to define for a feature is what the name of the feature is and which feature group it belongs to. The name of the feature will appear as a link underneat the feature group. There are some already existing groups that you can attach your documentation to or you can build your own group name and that will be added to the list of documented features in the generated feature documentation.
| Feature Taglets | |
|---|---|
| Taglet | Description |
| @dtf.feature name | The name of the feature being documented. |
| @dtf.feature.group group | The logical group belongs to within the documentation being generated. This is going to be used to display this feature within the same group as as other features with the same group name. |
| @dtf.feature.desc desc | The description of this feature along with any information that might be useful for the test writers that may find this feature to be useful. You can place almost any HTML elements in this section which allows you to format your documentation nicely using tables and lists. |
| @dtf.example example | This tag can be used to identify example XML documentation that shows exact XML samples of how to use the feature being documented. So the body of this taglet can be any XML you'd like just be sure to place a single root element around your XML. |